Context

This PR adds a SmartScrollbar component to @ohif/ui-next that visualizes slice loading progress, viewed state, and scroll position in viewports.

The component is pure UI — it has no Cornerstone or viewer dependencies. It accepts a slice index, total count, loading state, and Sets of loaded/viewed indices, and handles all measurement, animation, pointer interaction, and visual state internally.

Preview the component, animations, and behaviors here: https://ohif-scroll-design-final.netlify.app/

Changes & Results

New files — 7 component files in platform/ui-next/src/components/SmartScrollbar/:

Modified — platform/ui-next/src/components/index.ts to export the new components.

Usage:

<SmartScrollbar value={index} totalSlices={295} onValueChange={setIndex} isLoading={loading}>
  <SmartScrollbarTrack>
    <SmartScrollbarFill slices={loadedSet} className="bg-neutral/25" loadingClassName="bg-neutral/50" />
    <SmartScrollbarFill slices={viewedSet} className="bg-primary/35" />
  </SmartScrollbarTrack>
  <SmartScrollbarIndicator />
  <SmartScrollbarEndpoints slices={loadedSet} />
</SmartScrollbar>

Key behaviors:

• Track contracts from 8px to 4px after loading completes (600ms settle delay, 300ms ease transition)
• Expands on hover or drag
• Dot-grid pattern fades in during loading, fades out on completion
• Loaded fill brightens during loading (50% opacity), dims after (25%)
• Endpoint caps stay stationary during contraction (rendered via portal to a stable layer)
• Click-to-jump and drag-to-scrub with pointer capture
• Error thrown if SmartScrollbarIndicator is omitted
• Uses existing OHIF design tokens (--neutral, --primary, --foreground)
• Fill colors are consumer-configurable via Tailwind class props

Testing

No Testing Needed.

This PR adds a UI component only — no viewer integration is included. The component can be previewed and tested interactively here:

Live demo: https://ohif-scroll-design-final.netlify.app/

• Press Play to see the loading lifecycle (dot-grid, fills, contraction)
• Scroll the viewport to move the indicator
• Hover the contracted scrollbar to see it expand
• Drag the indicator to scrub through slices

Checklist

PR

• My Pull Request title is descriptive, accurate and follows the
  semantic-release format and guidelines.

Code

• My code has been well-documented (function documentation, inline comments,
  etc.)

Public Documentation Updates

• The documentation page has been updated as necessary for any public API
  additions or removals.

Tested Environment

• OS: macOS Sequoia 15.7.4 (24G517), Apple M4 Pro
• Node version: 20.19.1
• Browser: Google Chrome (latest) 146.0.7680.165 (Official Build) (arm64)

Greptile Summary

This PR introduces SmartScrollbar, a pure-UI compound component for @ohif/ui-next that visualises slice loading progress, viewed state, and current scroll position in viewports. The implementation is self-contained with no Cornerstone or viewer dependencies, accepting a value, total, onValueChange, and isLoading prop alongside Uint8Array-backed fill/endpoint children.

Key design choices and outcomes:

• Pixel-space rendering via computePixelFilledFromMarked prevents fills from overstating coverage when many slice indices map to a single pixel row.
• useByteArray hook manages the mutable Uint8Array + incrementing version pattern so fill components re-render correctly even when the array is mutated in-place; an optional debounceMs batches high-frequency cache events.
• Stable layer + createPortal ensures SmartScrollbarEndpoints caps don't shift during the track contraction animation; the previously flagged ref-timing bug is fixed with a useState callback ref.
• Opt-in keyboard navigation (enableKeyboardNavigation, default false) avoids conflicts with OHIF's existing keyboard shortcuts while keeping WAI-ARIA slider compliance available.
• ByteArrayHandle and SmartScrollbarLayoutContextValue types are correctly exported from the inner barrel (SmartScrollbar/index.ts) but are not forwarded from the top-level src/components/index.ts, so consumers of @ohif/ui-next cannot import these types from the package root without deep-path imports.

Confidence Score: 5/5

• Safe to merge — all prior P1 concerns are resolved; the only remaining finding is a minor missing type re-export at the package entry point.
• All previously flagged issues (stale fills, endpoint ref timing, unconditional keyboard event capture, dead svgIdPrefix, run-length overflow) have been addressed. The sole remaining finding is a P2 omission: ByteArrayHandle and SmartScrollbarLayoutContextValue are not re-exported from the top-level src/components/index.ts, limiting type discoverability for package consumers. This does not affect runtime behaviour and does not block merge.
• platform/ui-next/src/components/index.ts — missing type re-exports for ByteArrayHandle and SmartScrollbarLayoutContextValue.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    SSB["SmartScrollbar\n(root — context provider,\nResizeObserver, pointer & keyboard handling)"]

    LC["SmartScrollbarLayoutContext\n(total, trackHeight, isLoading,\neffectiveWidth, trackWidth,\nfillPadding, stableLayerEl)"]
    SC["SmartScrollbarScrollContext\n(value: number)"]

    SSB --> LC
    SSB --> SC

    SST["SmartScrollbarTrack\n(dot-grid background,\nfades in/out with isLoading)"]
    SSF["SmartScrollbarFill\n(colored bars for contiguous runs;\nmarked: Uint8Array + version)"]
    SSI["SmartScrollbarIndicator\n(pill-shaped position marker;\nrequired child)"]
    SSE["SmartScrollbarEndpoints\n(SVG caps at loaded range boundaries;\nportaled into stable layer)"]

    LC --> SST
    LC --> SSF
    LC --> SSI
    LC --> SSE
    SC --> SSI

    UBA["useByteArray(size, debounceMs?)\n→ ByteArrayHandle\n(bytes, version, isFull,\nsetByte, clearByte, resetWith)"]

    UBA -->|"marked + version"| SSF
    UBA -->|"marked + version"| SSE

    UTILS["utils.ts\ncomputePixelFilledFromMarked()\ncomputeContiguousRuns()\ngetIndicatorLayout()"]

    SSF --> UTILS
    SSE --> UTILS
    SSI --> UTILS
    SSB --> UTILS

    SL["Stable layer div\n(absolute, full size,\npointerEvents: none)"]
    SSB --> SL
    SSE -->|"createPortal"| SL

_{Reviews (4): Last reviewed commit: "Add unit tests for SmartScrollbar utils ..." | Re-trigger Greptile}